/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University. All rights reserved.
 * 
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 * 1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license; 2) All redistributions in binary form
 * must reproduce the above copyright notice, this list of conditions and the
 * disclaimer listed in this license in the documentation and/or other materials
 * provided with the distribution; 3) Any documentation included with all
 * redistributions must include the following acknowledgement:
 * 
 * "This product includes software developed by the Community Grids Lab. For
 * further information contact the Community Grids Lab at
 * http://communitygrids.iu.edu/."
 * 
 * Alternatively, this acknowledgement may appear in the software itself, and
 * wherever such third-party acknowledgments normally appear.
 * 
 * 4) The name Indiana University or Community Grids Lab or NaradaBrokering,
 * shall not be used to endorse or promote products derived from this software
 * without prior written permission from Indiana University. For written
 * permission, please contact the Advanced Research and Technology Institute
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202. 5) Products
 * derived from this software may not be called NaradaBrokering, nor may Indiana
 * University or Community Grids Lab or NaradaBrokering appear in their name,
 * without prior written permission of ARTI.
 * 
 * 
 * Indiana University provides no reassurances that the source code provided
 * does not infringe the patent or any other intellectual property rights of any
 * other entity. Indiana University disclaims any liability to any recipient for
 * claims brought by any other entity based on infringement of intellectual
 * property rights or otherwise.
 * 
 * LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO
 * WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 * NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF
 * INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS.
 * INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS",
 * "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.
 * LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR
 * ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION
 * GENERATED USING SOFTWARE.
 */
package cgl.narada.event;


/**
 * This class encapsulates various headers which indicate, among other things,
 * if the event is (a) Persistent or transient (b) Has Correlation identifers
 * (c) Security and Integrity related information (d) Fragmentation and Slicing
 * related information (e) Compressed
 * 
 * @author Shrideep Pallickara 
 * $Date$ 
 * $Revision$
 */

public interface EventHeaders {

    /** Indicates the templateId which this event conforms to */
    public int getTemplateId();

    /**
     * Returns the timestamp for this event. This timestamp corresponds to the
     * value assigned by the time service
     */
    public long getTimeStamp();

    /** Returns the generator of this message */
    public int getSource();

    /**
     * Indicates that the message should not be rerouted to it source, that is
     * contained in the event headers
     */
    public boolean supressDistributionToSource();

    /** Indicates if there is an event id associated with this message */
    public boolean hasEventId();

    /** Get the event identifier */
    public EventID getEventId();

    /**
     * Indicates if this event is correlated with any other event. Casual
     * constraints may entail that the correlated event be delivered prior to
     * the delivery of this event.
     */
    public boolean isCorrelated();

    /** Returns the correlation identifier associated with the event */
    public EventID getCorrelationIdentifier();

    /** Returns the time to live */
    public int getTimeToLive();

    /** Indicates if this event is a secure event */
    public boolean isSecure();

    /** Indicates if the event has a signature associated with it */
    public boolean hasSignature();

    /**
     * Retrieves the signature Algorithm. Available <i>only<i> if this is a
     * secure event.
     */
    public String getSignatureAlgorithm();

    /**
     * Retrieve the signature associated with event. Available <i>only<i> if
     * this is a secure event
     */
    public byte[] getSignature();

    /** Indicates if there is an IV associated with the encrypted payload */
    public boolean hasCipherIV();

    /**
     * Retrieves the IV associated with the encrypted payload. Available <i>only<i>
     * if this is a secure event
     */
    public byte[] getCipherIV();

    /**
     * Retrieves the Cipher mode. Available <i>only<i> if this is a secure
     * event
     */
    public String getCipherMode();

    /**
     * Retrieves the Cipher padding scheme. Available <i>only<i> if this is a
     * secure event
     */
    public String getCipherPaddingScheme();

    /** Indicates if there are security assertions encapsulated in this event. */
    public boolean hasAssertions();

    /**
     * Retrieve SAML Assertions. Available <i>only<i> if this is a secure event
     */
    public String getAssertions();

    /** Indicates if the event has integerity check information. */
    public boolean hasIntegrity();

    /**
     * Returns the message digest scheme used for computing the digest.
     * Available <i>only<i> if this is a secure event or has integrity
     */
    public String getMessageDigestScheme();

    /**
     * Gets the message digest for the payload. Available <i>only<i> if this is
     * a secure event or has integrity
     */
    public byte[] getMessageDigest();

    /** Indicates if this event is a fragment of a larger event */
    public boolean isFragmented();

    /**
     * Returns the fragmentation identifier associated with this fragment.
     * Fragments that are part of the same event have the same fragmentation
     * identifier, though each of them might have different event identifiers
     */
    public String getFragmentationIdentifier();

    /**
     * Indicates if this is the last fragment in the series of fragmented events
     */
    public boolean isLastFragment();

    /** Gets the fragment number associated with this fragment */
    public int getFragmentNumber();

    /**
     * Indicates if there is information pertaining to the total number of
     * fragments
     */
    public boolean hasTotalNumberOfFragmentsInfo();

    /** Gets the fragment number associated with this fragment */
    public int getTotalNumberOfFragments();

    /** Gets the epoch associated with the fragmentation */
    public long getFragmentationEpoch();

    /*
     * Indicates if this is an event slice which contains a part of the orginal
     * transmitted payload. These are specifically used in cases where the
     * device might not prefer the retransmission of the entire event
     */
    public boolean isSliced();

    /**
     * Gets the slice from which point on the payload is included. For example
     * one may be interested in the payload from size 90026 to 190000
     */
    public int getSliceStartingPoint();

    /** Gets the slice ending point */
    public int getSliceEndingPoint();

    /** Indicates if this event includes priority information */
    public boolean hasPriorityInfo();

    /** Gets the priority associated with this event */
    public int getPriority();

    /** Gets the application type associated with this event */
    public String getApplicationType();

    /**
     * Indicates if the event is a persistent one. If it is, the event needs to
     * be archived on storage. It is of course assumed that the event
     * corresponds to a template that supports reliable delivery
     */
    public boolean isPersistent();

    /**
     * Indicates if this event is a transient event. If this is a transient
     * event it need not be archived on any storage
     */
    public boolean isTransient();

    /**
     * Indicates if the payload has been compressed. Such events are
     * specifically used in cases where the device's network utilization costs
     * might be at a premium.
     */
    public boolean isCompressed();

    /** Get information regarding the compresssion algorithm being used */
    public String getCompressionAlgorithm();

    /**
     * Gets the original payload length prior to compression. Will return ZERO
     * if the event doesn't have a compressed payload
     */
    public long getOriginalPayloadLength();

    /**
     * Indicates if the payload was compressed after operations such as
     * securing, computing message digests were performed
     */
    public boolean isPayloadCompressionFinalStep();

    /** Get a byte stream representation of the event headers */
    public byte[] getBytes();

    // HG: Security related stuff...

    public byte[] getSignedSecurityToken();

    public void setSecurityToken(byte[] token);

    public void setSignatureInformation(String signatureAlgorithm,
            byte[] signature);

    public void setEncryptedPayloadInformation(byte[] cipherIV,
            String cipherMode, String cipherPaddingScheme);

    public byte[] getSecurityTimeStampedSeqNo();

    public void setSecurityTimeStampedSequenceNo(byte[] obj);

    // -----
    
    /** Indicates if the EventHeader has been modified since the last time
     * that it was serialized. */
    public boolean isModified();
}
